Finalize UI truthfulness and bootstrap hardening
This commit is contained in:
master
@@ -10,6 +10,22 @@ This guide covers the current `stella setup` command set for installation-scoped
|
||||
- It uses the Platform setup session APIs as the source of truth. Local files are not the authoritative setup state.
|
||||
- Tenant onboarding such as integrations, secrets providers, advisory sources, environments, agents, and notifications happens on the authenticated `/setup/*` surfaces and the corresponding CLI command groups.
|
||||
|
||||
## Retained Secrets
|
||||
|
||||
- Setup session `draftValues` remain sanitized. Passwords and similar secret-bearing fields are not echoed back through normal session reads.
|
||||
- When the backend needs a secret to survive resume/apply, it retains that value in protected companion storage and exposes only `secretDrafts` metadata in `stella setup status --json`.
|
||||
- Re-running or resuming setup without re-entering a retained secret keeps the server-retained value for probe/apply.
|
||||
- Supplying a new secret value replaces the retained one for that setup session.
|
||||
- Backend protection key precedence is `Platform:Setup:SecretProtectionKey`, `STELLAOPS_SECRETS_ENCRYPTION_KEY`, then `STELLAOPS_BOOTSTRAP_KEY`.
|
||||
|
||||
## Operational Readiness
|
||||
|
||||
- `stella setup status` reports required control-plane readiness only.
|
||||
- Text output prints an `Operational readiness` section with the current required counts, blocker summary, and any blocking dependencies.
|
||||
- `stella setup status --json` includes a `readiness` object for automation. This payload is intentionally required-only; optional post-boot services are not mixed into setup gating.
|
||||
- `stella setup run` finalization stops with an explicit error if any required readiness dependency is still blocked.
|
||||
- Optional post-boot services belong to `stella admin diagnostics health`, not to setup completion.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
@@ -35,6 +51,29 @@ stella setup reset --step cache
|
||||
stella setup reset --all --force
|
||||
```
|
||||
|
||||
## First Auth After Setup
|
||||
|
||||
Fresh local/dev installs seed first-party CLI auth clients through `etc/authority/plugins/standard.yaml`.
|
||||
|
||||
Human operators:
|
||||
|
||||
```bash
|
||||
stella auth login
|
||||
```
|
||||
|
||||
- The CLI defaults to the seeded human client `stellaops-cli`.
|
||||
- In a fresh interactive shell, if no Authority username/password is preconfigured, the CLI prompts and uses the current password-grant bootstrap path.
|
||||
|
||||
Automation:
|
||||
|
||||
```bash
|
||||
export STELLAOPS_AUTHORITY_CLIENT_ID=stellaops-cli-automation
|
||||
export STELLAOPS_AUTHORITY_CLIENT_SECRET=stellaops-local-cli-automation-secret
|
||||
stella auth login --json
|
||||
```
|
||||
|
||||
Production deployments should replace local/dev secrets and can tighten the allowed grants for these first-party clients.
|
||||
|
||||
## Supported Steps
|
||||
|
||||
| Step | Purpose | Notes |
|
||||
@@ -91,7 +130,11 @@ Show the current installation-scoped session.
|
||||
|
||||
Options:
|
||||
- `--session` - explicit setup session ID
|
||||
- `--json` - machine-readable output
|
||||
- `--json` - machine-readable output including sanitized `draftValues` and retained-secret `secretDrafts` metadata
|
||||
|
||||
Notes:
|
||||
- The status surface carries required-only readiness because setup is allowed to finish before optional post-boot services come online.
|
||||
- Use `stella admin diagnostics health` when you need the full required-plus-optional platform readiness view.
|
||||
|
||||
### `stella setup reset`
|
||||
|
||||
@@ -146,13 +189,34 @@ crypto:
|
||||
|
||||
When `stella setup` finishes, the next work is tenant onboarding, not more bootstrap steps.
|
||||
|
||||
Typical next commands:
|
||||
If you are bringing up the Stella-owned local compose fixture lane, authenticate first and use the owned fixture bootstrap command:
|
||||
|
||||
```bash
|
||||
# Authenticate into the target tenant if needed
|
||||
stella auth login
|
||||
|
||||
# Bootstrap the default 13-entry local fixture catalog
|
||||
stella config integrations bootstrap local
|
||||
|
||||
# Add the owned local GitLab SCM and CI fixtures
|
||||
stella config integrations bootstrap local --include-gitlab
|
||||
|
||||
# Also add the optional local GitLab registry fixture
|
||||
stella config integrations bootstrap local --include-gitlab --include-gitlab-registry
|
||||
```
|
||||
|
||||
The local bootstrap contract is explicit:
|
||||
- default mode creates or updates the 13 deterministic local compose entries and verifies their health
|
||||
- `--include-gitlab` mints the owned local GitLab PAT, stages it through Secret Authority into Vault, then binds GitLab Server and GitLab CI with the returned `authref://...` values
|
||||
- `--include-gitlab-registry` adds the optional GitLab container registry entry for the heavy GitLab compose profile with registry enabled via `GITLAB_ENABLE_REGISTRY=true`
|
||||
|
||||
For production or customer-managed third-party systems, use bring-your-own-secret onboarding instead of the local fixture bootstrap:
|
||||
|
||||
```bash
|
||||
# Discover writable secret-authority targets
|
||||
stella config integrations secrets targets
|
||||
|
||||
# Stage a GitLab access token into a secret-authority target
|
||||
# Stage an operator-provided GitLab access token into a secret-authority target
|
||||
stella config integrations secrets upsert-bundle \
|
||||
--bundle gitlab-server \
|
||||
--target <vault-integration-id> \
|
||||
@@ -161,10 +225,10 @@ stella config integrations secrets upsert-bundle \
|
||||
|
||||
# Create the GitLab server integration with the returned authref
|
||||
stella config integrations create \
|
||||
--name local-gitlab \
|
||||
--name customer-gitlab \
|
||||
--type scm \
|
||||
--provider gitlabserver \
|
||||
--endpoint http://gitlab.stella-ops.local:8929 \
|
||||
--endpoint https://gitlab.example.com \
|
||||
--authref authref://vault/gitlab/server#access-token
|
||||
```
|
||||
|
||||
@@ -197,11 +261,24 @@ Check:
|
||||
- the runtime cache service is reachable
|
||||
- the host/port/password values are correct
|
||||
|
||||
### Setup finalization is blocked by operational readiness
|
||||
|
||||
```bash
|
||||
stella setup status --json
|
||||
stella admin diagnostics health --detail
|
||||
```
|
||||
|
||||
Check:
|
||||
- which required dependency is still reported as `blocked` in the setup status `readiness` payload
|
||||
- whether `frontdoor` or `authority` is failing its live probe
|
||||
- whether optional post-boot service degradation is being mistaken for a setup blocker
|
||||
|
||||
### Setup reports that `vault` or `scm` is no longer a supported step
|
||||
|
||||
That is expected. Those flows moved out of installation bootstrap.
|
||||
|
||||
Use:
|
||||
- `stella config integrations bootstrap local` for the Stella-owned local compose fixture lane
|
||||
- `stella config integrations secrets *`
|
||||
- `stella config integrations create`
|
||||
- the authenticated `/setup/integrations/*` UI
|
||||
@@ -209,6 +286,7 @@ Use:
|
||||
## Related Commands
|
||||
|
||||
- `stella setup status --json`
|
||||
- `stella config integrations bootstrap local`
|
||||
- `stella config integrations providers`
|
||||
- `stella config integrations secrets targets`
|
||||
- `stella config integrations secrets upsert-bundle`
|
||||
|
||||
Reference in New Issue
Block a user