API and clients¶
The Pebble daemon exposes an API (HTTP over a unix socket) to allow remote clients to interact with the daemon. It can start and stop services, add configuration layers to the plan, and so on.
If pebble run
is started with the --http <address>
option, Pebble also exposes open-access HTTP endpoints using the given TCP address (see API access levels below).
There is currently no official documentation for the API at the HTTP level (apart from the code itself!); most users will interact with it via the Pebble command line interface or by using the Go or Python clients.
The Go client is used primarily by the CLI, but is importable and can be used by other tools too. See the reference documentation and examples at pkg.go.dev.
We try to never change the underlying HTTP API in a backwards-incompatible way, however, in rare cases we may change the Go client in a backwards-incompatible way.
In addition to the Go client, there’s also a Python client for the Pebble API that’s part of the ops
library used by Juju charms (documentation here).
API access levels¶
API endpoints fall into one of four access levels, from least restricted to most restricted:
Open-access - Allowed from any user, even unauthenticated users using the HTTP-over-TCP listener.
GET /v1/system-info
, which returns the Pebble version and other informationGET /v1/health
, which returns a boolean to indicate whether Pebble’s health checks are all healthy
Metrics-access - Allowed from any authenticated user or any user that has been granted
metrics
access.GET /v1/metrics
, which returns metrics for services and health checks in OpenMetrics format.
Read-access - Allowed from any authenticated user. For example, listing services or viewing notices.
All
GET
endpoints except the admin-accessGET
endpointsPOST /v1/notices
, which records a custom notice
Admin-access - Only allowed from admin users. For example, adding a layer or starting a service.
GET /v1/files
, which pulls a file from a remote systemGET /v1/tasks/{task-id}/websocket/{websocket-id}
All
POST
endpoints exceptPOST /v1/notices
(which is read-access)
Pebble authenticates clients that connect to the socket API using peer credentials (SO_PEERCRED
) to determine the user ID (UID) of the connecting process. If this UID is 0 (root) or the UID of the Pebble daemon, the user’s access level is admin
, otherwise the access level is read
.
If Pebble can’t authenticate the user, the user’s access level is untrusted
. Unauthenticated users can only use open-access endpoints.
Pebble doesn’t try to authenticate users that connect over TCP. So any user that connects over TCP is unauthenticated (access level untrusted
) and can only use open-access endpoints.
Controlling API access using identities¶
In addition to the default access control, Pebble admins can also set up named identities with specific access levels using the identities CLI commands.
Each identity has a name, an access level, and an authentication type with type-specific configuration.
Currently the supported authentication types are:
local
: a local user ID determined using peer credentials.basic
: HTTP basic authentication.
An example admin identity named “bob” with local
type is shown below:
identities:
bob:
access: admin
local:
user-id: 42
An example identity named “alice” with basic
type and metrics
access level is shown below:
identities:
alice:
access: metrics
basic:
# The password is hashed using sha512-crypt, as generated by "openssl passwd -6".
password: <password hash>
Read how to manage identities for more information.