Skip to content

Setting up the provider console

In short

Section titled “In short”

The console is off until you switch it on, and it only switches on for a hosted installation. You give it a listener of its own, decide which networks may reach it, and create the first owner from the command line. Everyone else is invited from inside the console.

Before you start

Section titled “Before you start”
  • The installation is a hosted one: SP_DEPLOYMENT=saas. With any other value SpeculaPro refuses to start: config: SP_PROVIDER_CONSOLE_ENABLED needs SP_DEPLOYMENT=saas; a self-hosted installation has no provider console.
  • SP_DB_SYSTEM_URL is set for the processes that run the api role (and for the command line when you create staff). The console’s tables answer the system database role only; the application role can neither read nor write them.
  • SP_SECURITY_COOKIE_SECURE=true, as on any installation outside development. The console’s session cookie never travels over plain HTTP.
  • Migrations are applied.

Settings

Section titled “Settings”
Setting Default What it does
SP_PROVIDER_CONSOLE_ENABLED false true serves the console. Only with SP_DEPLOYMENT=saas
SP_PROVIDER_ADDR none The console’s own listener, for example :8090. Required when the console is on, and it must not be SP_HTTP_ADDR or SP_METRICS_ADDR
SP_PROVIDER_ALLOWED_CIDRS empty Comma-separated networks staff may come from, for example 10.8.0.0/16,203.0.113.7/32. A bare address means that one host. Requests from anywhere else are answered 403 not allowed from this network before anything else is looked at. Empty: whoever the network lets through
SP_PROVIDER_SESSION_IDLE 30m How long a session may sit unused before it ends. Between 1m and 1h
SP_PROVIDER_SESSION_TTL 8h The longest a session lasts, whatever is done in it. Between SP_PROVIDER_SESSION_IDLE and 12h
SP_PROVIDER_PURGE_ENABLED false true lets the worker delete a workspace whose scheduled deletion is due. Set it the same for the worker and api processes: the console shows which of the two behaviours applies. Only with SP_DEPLOYMENT=saas. See Scheduled deletion

SP_PROVIDER_DEV_NO_TOTP exists for development only. With any SP_ENV other than development, SpeculaPro refuses to start with it set: provider staff always sign in with a second factor.

The console is served by the api role, so it runs wherever that role runs. Scheduled deletion and the hourly usage count are done by the worker role.

How the client address is decided

Section titled “How the client address is decided”

SP_PROVIDER_ALLOWED_CIDRS is checked against the address SpeculaPro decides the request came from, the same way as for the customer API: a forwarding header is believed only from the proxies you configured with SP_HTTP_TRUST_PROXY and SP_HTTP_PROXY_HOPS. If the console sits behind a proxy and those are not set, every request appears to come from the proxy.

/healthz on the console’s listener stays open to every address, so your platform’s probes work. It answers 204 and says nothing. /readyz checks the database.

Where the console lives

Section titled “Where the console lives”
Address on the console’s listener What
/provider/ The console’s web app
/provider/api/v1/… Its API. See Provider console API
/healthz, /readyz Probes

The customer listener has no route to any of these, and the console’s listener has no route to the customer app or API. The two share no cookie: the console’s is named __Secure-sp_provider and is scoped to /provider.

With Helm

Section titled “With Helm”
Value Default What it does
providerConsole.enabled false Switches the console on. The chart fails to render unless deployment is saas, and refuses it for the global directory (mode: directory): the console belongs to a region
ports.provider 8090 The console’s listener on the api pods. Must differ from ports.http and ports.metrics
providerConsole.allowedCIDRs [] SP_PROVIDER_ALLOWED_CIDRS
providerConsole.sessionIdle, providerConsole.sessionTtl 30m, 8h The two session settings
providerConsole.purge.enabled false SP_PROVIDER_PURGE_ENABLED
providerConsole.service.type ClusterIP The console gets a Service of its own, <release>-provider, on port 80. Use LoadBalancer with an internal-only annotation for a private load balancer
providerConsole.service.annotations, .loadBalancerClass, .loadBalancerSourceRanges empty Passed to that Service
networkPolicy.providerFrom [] Who may reach ports.provider on the api pods. Empty means nobody: the port stays closed until you name the VPN gateway’s or the internal proxy’s pods or addresses

No Ingress of the chart routes to the console. A minimal example:

deployment: saas
providerConsole:
  enabled: true
  allowedCIDRs: ["10.8.0.0/16"]
  service:
    type: ClusterIP
networkPolicy:
  providerFrom:
    - ipBlock: {cidr: 10.8.0.0/16}

With the console on, the chart also installs two alerts, SpeculaProWorkspaceOverPlanLimit and SpeculaProWorkspaceDeletionWaiting. See Plans and limits and Suspending and deleting.

How to create the first owner

Section titled “How to create the first owner”

Nobody can sign in to a new console, so the first owner is made from the command line.

  1. Run the command where SpeculaPro’s configuration is available, with SP_DB_SYSTEM_URL set:

    Terminal window
    speculapro provider staff create --email [email protected] --name 'Ada Mensah'

    On Kubernetes:

    Terminal window
    kubectl exec deploy/<release>-api -- speculapro provider staff create \
      --email [email protected] --name 'Ada Mensah'

  2. Note the temporary password it prints. It is shown once, works for 72 hours, and must be changed at the first sign-in.

  3. Open https://<the console's address>/provider/ and sign in with the email and the temporary password.

  4. Choose a new password (at least 12 characters).

  5. Scan the QR code with an authenticator app and enter the six-digit code it shows.

The account is an Owner unless you pass --role. From here, invite everyone else from the Staff page. Create a second owner soon: the last active owner can’t be deactivated or demoted, and nobody can reset their own second factor.

If the command prints note: the console is off (SP_PROVIDER_CONSOLE_ENABLED); nobody can sign in until it is switched on, the account exists but the listener isn’t serving yet.

See Staff and roles for the other commands.

Monitoring

Section titled “Monitoring”
Metric Type Labels What it counts
speculapro_provider_logins_total Counter result (success, failure, rate_limited) Sign-in attempts at the console. Alert on a burst of failures
speculapro_provider_actions_total Counter action Entries written to the console’s audit log, by action
speculapro_provider_sessions_active Gauge Console sessions that would still be accepted, sampled every minute
speculapro_provider_workspaces_over_limit Gauge limit (users, events) Active workspaces over what their plan agreed, sampled every minute
speculapro_provider_workspaces_purged_total Counter Workspaces deleted by the worker after their scheduled date
speculapro_provider_purge_waiting Gauge reason Workspaces whose scheduled date has passed and that are not deleted

No workspace and no member of staff is ever a metric label; the audit log says who did what.

Section titled “Related”