Documentation
¶
Overview ¶
Package dashboard prepares the Ceph Dashboard of an existing cluster as a collaborator for an application that consumes its REST API: an owned HTTPS listener with the caller's certificate, an owned account with one role, the endpoint of the active manager after an authenticated readiness check, and optionally the RGW backend of one owned gateway with a dedicated read-only RGW identity.
The Dashboard backend runs inside ceph-mgr, so the cluster's managers must run an image that ships the dashboard module and its frontend, such as the official Ceph image selected through ceph.ImageSet.MGR; the essential role image does not. Start acts on a cluster that ceph.Run or a service package's Run started; it starts no container. Dashboard requests and application workflows remain the SUT's: the package adds no Dashboard client.
Index ¶
- Constants
- Variables
- type Config
- type Dashboard
- func (d *Dashboard) AddGateway(ctx context.Context, gateway *rgw.Gateway) (*GatewayLink, error)
- func (d *Dashboard) Credentials() (username, password string)
- func (d *Dashboard) Endpoint(ctx context.Context) (string, error)
- func (d Dashboard) Format(f fmt.State, _ rune)
- func (d Dashboard) GoString() string
- func (d *Dashboard) HostEndpoint(ctx context.Context) (string, error)
- func (d *Dashboard) Restore(ctx context.Context) error
- func (d Dashboard) String() string
- type GatewayLink
- type TLSConfig
Constants ¶
const GatewayAdminCaps = "users=read;buckets=read;metadata=read"
GatewayAdminCaps are the RGW Admin Ops capabilities of the identity that AddGateway creates for the Dashboard: metadata=read lets the Dashboard open its connection to the gateway, users=read and buckets=read let it list and show users and buckets. Dashboard pages that change RGW state, or that read other RGW state, are refused by RGW with this identity.
Variables ¶
var ( // ErrGatewayRefused reports that the gateway answered the Dashboard and // refused its RGW identity, such as a wrong key, a suspended or removed // identity, or missing capabilities. ErrGatewayRefused = errors.New("the gateway refused the dashboard's RGW identity") // ErrGatewayUnreachable reports that the Dashboard could not reach the // gateway: a refused or timed-out connection, or a request that did not // finish within the probe's time. ErrGatewayUnreachable = errors.New("the dashboard cannot reach the gateway") )
Errors of GatewayLink.Check that attribute a failed RGW backend. Both come from the Dashboard's own answer while the Dashboard itself answered the owned account, so they are not a failure of the Dashboard's readiness.
Functions ¶
This section is empty.
Types ¶
type Config ¶
Config selects the listener certificate and the owned account of Start.
Username names the account; empty generates tc-dashboard-<random>. An account of that name must not exist: Start never adopts one. Role is the one role of the account, a built-in role such as read-only (the default), block-manager or administrator, or a role that already exists; Start creates no role. The password is generated and satisfies the Dashboard's default password policy. Username and Role each contain 1 to 64 ASCII characters, starting with a lowercase letter and followed by lowercase letters, digits, underscores, periods or hyphens. Start sets the account display name to a generated ownership marker. Keep that display name unchanged so Restore can verify the account before deletion.
type Dashboard ¶
type Dashboard struct {
// contains filtered or unexported fields
}
Dashboard is the Ceph Dashboard that Start prepared on one cluster. Copies share its state. Its methods are safe for concurrent use. Formatting it with any verb prints only its account name, never the password.
func Start ¶
Start enables the dashboard module of c, installs cfg.TLS as the certificate of every manager, creates the owned account and returns once the active manager's listener passed the readiness check of Endpoint.
In a host-network cluster every manager present at Start gets its own free host port on the cluster's public address, because the managers share the host's ports; a manager added later uses the module's default port 8443. The ports are reserved and released just before the module binds them, so a port another process takes in between fails the readiness check. In bridge mode the listener is the manager's container address on the cluster network with port 8443, which containers on that network reach; a process on the Docker host reaches it through the host port that ceph.WithManagerPorts(8443) publishes, at the URL of HostEndpoint.
The module's enabled state and the listener options are held through override handles, so a second Start on the same cluster, or an override.SetMGRModule of the dashboard module, is refused while a Dashboard is active. Start refuses a manager image without the dashboard module or with a dashboard module that cannot run, with ceph.ErrImageCapability and the module's native error, before any change.
A Start that fails after its first change returns the Dashboard together with the error: its Restore undoes what Start changed. Errors never contain the password, the private key or a session token.
func (*Dashboard) AddGateway ¶
AddGateway makes the Dashboard manage gateway, an owned gateway of the Dashboard's cluster that is the only RGW daemon in the cluster's service map. It creates a dedicated RGW user with GatewayAdminCaps through gateway, stores its key as the Dashboard's RGW API access and secret key (cluster-wide manager options, so every manager uses them after a failover), and returns once Check passes.
The Dashboard selects its gateway from the service map, not from a URL, so a cluster with more than one RGW daemon is refused before any change. It connects to the first frontend port the gateway advertises there, the plain HTTP listener that every fixture gateway serves, also one with TLS; the Dashboard's RGW TLS verification option is therefore not involved and not changed. A Dashboard has at most one link; the SUT's own RGW credentials are never used.
After attempting user creation, AddGateway may return a link with an error. Keep it for Remove, or call Dashboard.Restore. Cleanup checks for an unconfirmed user: an absent user needs no cleanup, and a present user with unconfirmed ownership is preserved and reported.
func (*Dashboard) Credentials ¶
Credentials returns the owned account's login name and password for the SUT. Keep its display name unchanged. Restore uses it as the ownership marker.
func (*Dashboard) Endpoint ¶
Endpoint returns the HTTPS URL of the active manager's Dashboard, as the MGR map advertises it, once that listener passed the readiness check: it presents the installed certificate on every connection of the check, it refuses the account with a wrong password, it accepts the account's password, and GET /api/summary with the session token is answered by the manager that the MGR map names active. The check compares the certificate of each connection before it sends a password or the session token, and sends nothing more after a mismatch. A standby answers with a redirect to the active manager, which the check refuses, so the call waits, within the cluster's startup timeout, until a failover settles. That timeout starts after admission. The initial state check can wait behind AddGateway or Restore even after the caller's context expires.
The URL is the one the MGR map advertises: in bridge mode the active manager's address on the cluster network, in host mode the cluster's public address and the manager's own port. A failover changes it; call Endpoint again after one. The check runs from the control container. A process on the Docker host of a bridge-mode cluster uses HostEndpoint.
func (*Dashboard) HostEndpoint ¶
HostEndpoint returns the HTTPS URL at which a process on the Docker host, such as the test process or a SUT that runs there, reaches the active manager's Dashboard. It runs the readiness check of Endpoint first, then connects from the calling process to the returned URL and requires the listener to present the installed certificate; that connection sends no request. As with Endpoint, the initial state check waits for admission before starting the probe timeout and can outlast the caller's deadline.
In bridge mode the URL is the Docker host and the host port that Docker mapped to the advertised port of the active manager's container, so the cluster must have been started with ceph.WithManagerPorts(8443), the module's port; without it HostEndpoint fails with ceph.ErrInvalidRequest. Every manager publishes its own host port, so a failover changes the URL: call HostEndpoint again after one. A standby's redirect names the active manager's container address, which the host may not reach, so the SUT follows the new HostEndpoint instead of the redirect. The host name differs from the advertised one; the SUT verifies the certificate's name, as with Endpoint, for example with the TLS server name. In host mode the URL is the one Endpoint returns.
func (*Dashboard) Restore ¶
Restore removes the gateway link of AddGateway, if any, deletes the owned account, puts the certificate and key that were stored before Start back (or removes them), removes the module's multi-cluster record when only the owned account wrote it, restores the module's enabled state and the listener options.
For an interrupted account, TLS or gateway API key write, Restore confirms the command has stopped before using the resource's state to complete that step. It verifies the account's display name against the ownership marker set at creation. Keep the display name unchanged. If it differs, Restore preserves the account and returns ceph.ErrInvalidRequest. An outside change to a certificate, key, listener option or module state that would be overwritten is refused. External account changes must not race the native read and delete commands. Restore still attempts the listener options. It keeps the module enabled until the preceding steps succeed, retains the fixture slot on error, and retries unfinished steps on the next call. When it disables the module it waits for the MGR map to withdraw the service. A deleted account is not an error. The module's own records, such as its access database and session-token signing key, stay. Restore is idempotent.
type GatewayLink ¶
type GatewayLink struct {
// contains filtered or unexported fields
}
GatewayLink is the RGW backend of a Dashboard that AddGateway wired to one owned gateway. Copies share its state. Formatting it prints only the RGW identity's ID.
func (*GatewayLink) Check ¶
func (l *GatewayLink) Check(ctx context.Context) error
Check asks the Dashboard, with the owned account, for its RGW daemons and users, and returns nil only when the Dashboard reports exactly the linked gateway, identified by its service map GID and port, and lists the link's own RGW user. An empty or partial answer is an error, never a pass.
It distinguishes the backend from the Dashboard: when the Dashboard itself does not pass the readiness check of Endpoint, that is the error; when it does and the gateway refuses the link's identity the error wraps ErrGatewayRefused, and when the Dashboard cannot reach the gateway it wraps ErrGatewayUnreachable. It makes one attempt.
func (GatewayLink) GoString ¶
func (l GatewayLink) GoString() string
GoString formats the link like String.
func (*GatewayLink) Remove ¶
func (l *GatewayLink) Remove(ctx context.Context) error
Remove restores the Dashboard's RGW API keys to what they were before AddGateway and removes the link's RGW user. A key that was changed or removed after AddGateway is refused with ceph.ErrInvalidRequest and left as it is; the user is still removed. Remove is idempotent and Dashboard.Restore calls it.
func (GatewayLink) String ¶
func (l GatewayLink) String() string
String names the link by its RGW identity.
func (*GatewayLink) User ¶
func (l *GatewayLink) User() *rgw.User
User returns the dedicated RGW identity that the Dashboard uses. A test suspends it to make the gateway refuse the Dashboard; it is removed by Remove and must not be removed otherwise.
type TLSConfig ¶
type TLSConfig struct {
CertificatePEM, PrivateKeyPEM []byte
}
TLSConfig is the certificate the Dashboard listener presents: a PEM certificate chain and its unencrypted RSA private key. The module verifies the pair with pyOpenSSL before it serves, and that check rejects other key types such as ECDSA, so Start refuses them. The fixture installs it for every manager of the cluster, so a manager that becomes active after a failover presents the same certificate. The SUT verifies it with its own trust anchor and the name in the certificate; the fixture never verifies a chain, it only checks that the listener presents this certificate.