Sicoob Customer CLI Quickstart

This runbook is the v1 operator path for Sicoob SREs running Finnest Power in their own AWS account. It assumes a compiled finnest binary installed with the matching finnest-runtime bundle. It does not require a Finnest monorepo checkout.

Prerequisites

• AWS account dedicated to the Finnest Power runtime.
• AWS credentials with permission to create and operate the Runtime CD state backend, platform stack, EKS runtime stack, Helm release, and smoke-test Kubernetes jobs.
• Kubeconfig for the target EKS cluster after platform provisioning.
• Finnest self-hosted license JWT delivered out-of-band by Finnest.
• Compiled finnest binary with one of:
  • adjacent finnest-runtime/ directory from the release tarball,
  • --runtime-source /path/to/finnest-runtime,
  • FINNEST_RUNTIME_SOURCE=/path/to/finnest-runtime.
• Operator credentials from Power IAM with these scopes for the target deployment id (aws-prod for production, aws-sandbox for sandbox):
  • infra.bootstrap:<deployment-id>
  • infra.deploy:<deployment-id>
  • infra.rollback:<deployment-id>
• Runtime CD deploy config JSON in a Customer-owned local file.
• Bootstrap config JSON in a Customer-owned local file.
• Runtime base URL available as RUNTIME_CD_BASE_URL for smoke checks.

For the Sicoob production path, use --cloud=aws --environment=prod. Sandbox verification uses --cloud=aws --environment=sandbox.

One-Time Init

Create a Customer workspace and keep config, evidence, and audit there:

mkdir -p ~/finnest-sicoob/runtime
cd ~/finnest-sicoob
cp /secure-drop/finnest-license.jwt ./finnest-license.jwt
cp /secure-drop/runtime-cd-bootstrap.json ./runtime/bootstrap.json
cp /secure-drop/runtime-cd-deploy.json ./runtime/deploy.json

Create the non-interactive init input:

{
  "cloudTarget": "aws",
  "environment": "prod",
  "region": "sa-east-1",
  "domain": "power.sicoob.example",
  "licensePath": "./finnest-license.jwt",
  "runtimeSource": "./finnest-runtime",
  "bootstrapConfigPath": "./runtime/bootstrap.json",
  "deployConfigPath": "./runtime/deploy.json",
  "owner": {
    "displayName": "Sicoob Owner",
    "email": "owner@sicoob.example",
    "method": "passkey"
  },
  "planeCapabilities": {
    "selfUpdate": false,
    "supportUpload": false,
    "catalogUpdates": false,
    "crashReports": false,
    "telemetry": false
  }
}

Then run init and set the runtime smoke inputs:

finnest init --non-interactive --config ./init.json
export RUNTIME_CD_BASE_URL="https://api.sicoob.example"
export KUBECONFIG="$HOME/.kube/aws-prod"

init writes ~/.finnest/config.toml and ./finnest.toml. Later commands read deployment.cloud, deployment.environment, runtime.source, runtime.bootstrap_config, and runtime.deploy_config from those files.

Authenticate the local Operator after Power IAM is reachable:

finnest auth login --power-url=https://power.sicoob.example
finnest auth whoami

Doctor

Run doctor before any mutating operation:

finnest doctor --cloud=aws --environment=prod

Do not continue until required checks are OK. Warnings such as license expiry should be reviewed before a production change window.

Bootstrap

Bootstrap provisions the Pulumi state backend for the deployment target:

finnest bootstrap --cloud=aws --environment=prod --yes

Review the evidence under:

.finnest/runs/bootstrap/<timestamp>-aws-prod/

The key files are bootstrap.json, state-backend.json, github-environment.env, and operator-next-steps.md.

Deploy Preview

Always preview first:

finnest deploy --cloud=aws --environment=prod --dry-run --json | tee deploy-preview.ndjson

Review the NDJSON stream. The final line is the command envelope; preceding lines are deploy phase events for preflight, preview, confirmation, Helm status, and smoke.

Deploy

Apply only after the preview is reviewed:

finnest deploy --cloud=aws --environment=prod --yes

Review:

.finnest/runs/deploy/<timestamp>-aws-prod/deploy.json

The deploy evidence mirrors the Runtime CD deploy output: target id, dry-run mode, status, engine version, platform summary, runtime summary, Helm phase, and smoke phase. Helm or smoke are never reported as passed unless those checks ran and passed.

Post-Deploy Doctor

Run doctor again after deploy:

finnest doctor --cloud=aws --environment=prod

If doctor fails, keep the deploy evidence directory and proceed to support bundle collection.

Rollback

Rollback imports the prior successful Pulumi deployment state for the runtime stack and then reruns smoke:

finnest rollback --cloud=aws --environment=prod --yes

Review:

.finnest/runs/rollback/<timestamp>-aws-prod/rollback.json

If rollback smoke fails, the command exits non-zero while keeping rollback evidence and the reverted revision pair. Do not treat the rollback as healthy until the smoke failure is resolved or explicitly accepted by the change owner.

Support Bundle

Create a redacted local support bundle:

finnest support bundle --json

If manual collection is required, include these directories and files:

.finnest/runs/doctor/
.finnest/runs/bootstrap/
.finnest/runs/deploy/
.finnest/runs/rollback/
.finnest/topology.json
.finnest/stack.json
.finnest/services/*.status.json
.finnest/resources/*.status.json

Do not include raw secrets, Pulumi passphrases, AWS secret keys, private keys, or unredacted .env files.

Plane Capability Toggles

The continuous plane-capability toggling command surface is tracked in #211. For the headless milestone, capability checks are explicit:

• Local Operator credentials must contain deployment-target-scoped capabilities.
• finnest doctor checks enabled plane capability endpoints from FINNEST_PLANE_CAPABILITIES_JSON.
• A disabled plane endpoint should be omitted or marked "enabled": false in that JSON.

Example:

[
  {
    "name": "support-bundle-upload",
    "url": "https://power.sicoob.example/capabilities/support-bundle",
    "enabled": false
  }
]

Supported v1 plane calls are limited to license refresh, telemetry, crash reports, support-bundle upload, regulatory catalog updates, and self-update. Runtime orchestration commands (bootstrap, deploy, rollback, secrets, and watch) do not call Finnest-hosted orchestration endpoints.

Troubleshooting

• RUNTIME_BUNDLE_MISSING: install the release finnest-runtime directory beside the binary, pass --runtime-source, or set FINNEST_RUNTIME_SOURCE.
• RUNTIME_BUNDLE_INVALID or RUNTIME_ASSET_MISSING: reinstall the runtime bundle from the same CLI release and verify finnest-runtime-bundle.json.
• BOOTSTRAP_CONFIG_FILE_MISSING: create the path referenced by RUNTIME_CD_BOOTSTRAP_CONFIG_PATH or [runtime].bootstrap_config.
• DEPLOY_CONFIG_FILE_MISSING: create the path referenced by RUNTIME_CD_DEPLOY_CONFIG_PATH or [runtime].deploy_config.
• DEPLOY_HELM_FAILED: inspect .finnest/runs/deploy/<run>/deploy.json and Helm output before retrying.
• DEPLOY_SMOKE_FAILED or ROLLBACK_SMOKE_FAILED: keep the evidence bundle, fix RUNTIME_CD_BASE_URL, kubeconfig, ingress, or health checks, then rerun doctor and the failed command.
• AUTH_POWER_URL_REQUIRED: pass --power-url, set FINNEST_POWER_URL, or configure [power].url after the self-hosted Power admin endpoint is live.