dashboard

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: MIT Imports: 25 Imported by: 0

README

Ceph Dashboard

Import github.com/JSYoo5B/ceph-testcontainers-go/dashboard to give an application that consumes the Ceph Dashboard REST API a real Dashboard on a disposable cluster: an HTTPS listener with the test's own certificate, an owned account with one role, the endpoint of the active manager after an authenticated readiness check, and optionally the Object Gateway pages backed by one owned gateway. Dashboard requests belong to the SUT; the package adds no Dashboard client and wraps no Dashboard operation. See API purpose and purpose tags.

Order of use

  1. Start a cluster whose managers ship the dashboard module. The essential role image does not; select a manager image that does, such as the official image of the same release, with ceph.ImageSet.MGR (see Releases and images). The other daemons keep their role images.
  2. Prepare the Dashboard with dashboard.Start(ctx, cluster, cfg). cfg.TLS is the certificate chain and RSA key the listener presents; the test keeps the CA. The module's certificate check rejects other key types, such as ECDSA, and the listener then never serves, so Start refuses them. cfg.Role selects the account's role (read-only by default) and cfg.Username its name (generated by default).
  3. Hand it to the SUT: Endpoint returns the active manager's HTTPS URL once that manager answered the owned account, and Credentials returns the account's name and password. The SUT verifies the certificate with the test's CA and the name in the certificate. A SUT on the Docker host of a bridge-mode cluster uses HostEndpoint instead, which needs the cluster started with ceph.WithManagerPorts(8443) (see Endpoints below).
  4. Meet a failover: after ceph mgr fail or a manager loss, call Endpoint (or HostEndpoint) again. It waits until the new active manager answers.
  5. Add the Object Gateway when the SUT uses the Dashboard's RGW pages: d.AddGateway(ctx, gateway) with an owned gateway from rgw.Start or rgw.Gateways. GatewayLink.Check asks the Dashboard for the gateway and the link's own RGW user; create the SUT's users and buckets with the rgw package and the S3 client under test.
  6. Clean up: d.Restore(ctx) removes the gateway link, deletes the account and puts the module and its options back, or terminate the cluster.
images := ceph.ImageSet{Essential: essential, Client: client, MGR: "quay.io/ceph/ceph:v20.2.4"}
cluster, err := ceph.Run(ctx, "", ceph.WithImageOptions(ceph.ImageOptions{}.WithImageSet(images)),
	ceph.WithClusterConfig(ceph.ClusterConfig{}.WithManagerCount(2)))
testcontainers.CleanupContainer(t, cluster)
if err != nil {
	t.Fatal(err)
}
d, err := dashboard.Start(ctx, cluster, dashboard.Config{TLS: dashboard.TLSConfig{CertificatePEM: cert, PrivateKeyPEM: key}})
if d != nil {
	t.Cleanup(func() {
		if err := d.Restore(context.Background()); err != nil {
			t.Errorf("restore dashboard: %v", err)
		}
	})
}
if err != nil {
	t.Fatal(err)
}
endpoint, err := d.Endpoint(ctx)
if err != nil {
	t.Fatal(err)
}
username, password := d.Credentials()
// Give the SUT endpoint, username, password and the CA of cert.

Concepts and limits

  • Readiness. Start and Endpoint pass only when the listener the MGR map advertises presents the installed certificate, refuses the account with a wrong password, accepts its password, and answers GET /api/summary with the session token from the manager that the MGR map names active. Every connection of the check compares the presented certificate with the installed one before it sends a password or the session token, so a stale or foreign listener receives neither, and the check sends nothing more after a mismatch. An open port, an enabled module or a module that can run is not readiness. The check runs from the control container. Each check sends one wrong password and then the right one, which resets the module's failed-login counter, so repeated checks never lock the account.
  • Endpoints. In bridge mode the listener is the manager's address on the cluster network, port 8443, which Endpoint returns: containers on that network reach it. A process on the Docker host reaches it only through a published port, and Docker publishes ports only when it creates a container, so start the cluster with ceph.WithManagerPorts(8443): every manager then publishes its own host port. HostEndpoint returns the Docker host and the active manager's port after the readiness check, and after a connection from the calling process that presents the installed certificate; it fails with ceph.ErrInvalidRequest when the managers publish no port. Its host name is not the certificate's name, so the SUT verifies the name it expects, for example with the TLS server name. A standby's redirect names the active manager's container address; a host-side SUT calls HostEndpoint again instead of following it. In a host-network cluster each manager present at Start gets a free host port on the public address, so the test process reaches the listener; a manager added later uses port 8443. The ports are reserved and released just before the module binds them, so another process can take one in between; Start then fails its readiness check. A failover changes the URL; there is no invariant URL. A standby answers every request with 303 See Other to the active manager's root URL.
  • Sessions. A session token is signed with the module's key, which all managers share: a token issued by one manager is accepted by the next active one. At every login the module records the account and its session token in the mgr/dashboard/MULTICLUSTER_CONFIG manager option, in plain text in ceph config dump; do not log that output. The fixture's password and the tokens of its readiness checks are masked in diagnostics reports.
  • Ownership. The module's enabled state and the host-mode listener options are held through override handles, so a second Start or an override.SetMGRModule of the module is refused while a Dashboard is active. The certificate and key are the module's cluster-wide config-keys; Restore puts back what was stored before Start only when they still hold the installed certificate, and refuses an outside edit, as the override handles do for the module and options. An existing account of the same name is refused, never adopted, and no role is created.
  • Restoration. Restore verifies the Dashboard account's display name before deletion. Keep the generated display name unchanged because it marks the account as owned by this fixture. It keeps the module enabled until the gateway link, account, multi-cluster record and certificate steps succeed. It still attempts the listener options, retains the fixture slot on error and retries the unfinished steps on the next call. The module keeps its access database and token signing key (mgr/dashboard/accessdb_v2, mgr/dashboard/jwt_secret) after Restore; they hold no fixture account.
  • Object Gateway. The Dashboard finds its gateway in the service map, so AddGateway needs the gateway to be the cluster's only RGW daemon. The Dashboard connects to the first frontend port the gateway advertises, its plain-HTTP listener, which a gateway with rgw.TLSConfig serves too; the Dashboard's RGW_API_SSL_VERIFY option is not involved and stays as it is. The link creates its own RGW user with GatewayAdminCaps (users=read;buckets=read;metadata=read, the least that lists users and buckets) and stores its key in the cluster-wide RGW_API_ACCESS_KEY and RGW_API_SECRET_KEY manager options, so every manager uses it after a failover. GatewayLink.Remove puts the prior values back only while the options still hold the link's key, and refuses an outside edit. The options are plain text in ceph config dump; the key is masked in diagnostics reports. It never uses the SUT's credentials or ceph dashboard set-rgw-credentials, which creates a system user. Pages that change RGW state are refused by RGW with this identity.
  • Backend failures. Check fails when the Dashboard's answer is empty or does not name the gateway and the link's user. With the Dashboard itself ready, an identity the gateway refuses (suspended, wrong key) is ErrGatewayRefused and an unreachable gateway is ErrGatewayUnreachable; a stopped gateway makes Dashboard RGW requests hang until the probe's time runs out, while login and Endpoint keep working.
  • Out of scope: Dashboard SSO, Grafana, Prometheus and Alertmanager pages, orchestrator-backed pages, multisite RGW and multi-cluster management.

Reference

The full contract of every type and function is in go doc: pkg.go.dev or go doc -all github.com/JSYoo5B/ceph-testcontainers-go/dashboard. See also Contexts and cleanup.

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

View Source
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

View Source
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

type Config struct {
	TLS      TLSConfig
	Username string
	Role     string
}

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

func Start(ctx context.Context, c *ceph.Container, cfg Config) (*Dashboard, error)

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

func (d *Dashboard) AddGateway(ctx context.Context, gateway *rgw.Gateway) (*GatewayLink, error)

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

func (d *Dashboard) Credentials() (username, password string)

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

func (d *Dashboard) Endpoint(ctx context.Context) (string, error)

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) Format

func (d Dashboard) Format(f fmt.State, _ rune)

Format prints String for every verb and flag.

func (Dashboard) GoString

func (d Dashboard) GoString() string

GoString formats the Dashboard like String.

func (*Dashboard) HostEndpoint

func (d *Dashboard) HostEndpoint(ctx context.Context) (string, error)

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

func (d *Dashboard) Restore(ctx context.Context) error

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.

func (Dashboard) String

func (d Dashboard) String() string

String names the Dashboard by its account without the password.

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.

func (TLSConfig) Format

func (c TLSConfig) Format(f fmt.State, _ rune)

Format prints String for every verb and flag.

func (TLSConfig) GoString

func (c TLSConfig) GoString() string

GoString formats the configuration like String, so %#v does not print the key.

func (TLSConfig) String

func (TLSConfig) String() string

String describes the configuration without the certificate or key.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL