Bootstrap Control State

Control Bootstrap is the canonical Control API automation example in the Caracal examples repository under controlBootstrap/. A small CI/CD-style pipeline keeps one workload environment - Application, Provider, Resource, and Policy - matching a declared plan without adding product-management verbs to the runtime CLI.

When to use it

Use it when CI must reconcile objects inside one existing zone through scoped Control credentials. Use the Admin SDK from a trusted operator environment when automation must create zones or use management surfaces not exposed by Control.

Prerequisites

• A ready runtime and existing target zone.
• Separate Control keys for apply, verify, and teardown with only documented scopes.
• A reviewed plan containing no production secrets.

What it demonstrates

Area	Behavior
Automation surface	Calls /v1/control/invoke instead of using a root admin token.
Identity model	Uses scoped, short-lived control keys created in the web console, one scope tier per pipeline stage.
Reconciliation	apply creates missing objects, patches drifted ones, and publishes a new policy version on content drift.
CI gating	verify is a read-only drift check that exits non-zero when the zone does not match the plan.
Safety model	Uses replay protection, rate limits, scoped control permissions, and audit.

The plan describes the PiperNet reporter’s environment: its Application, the provider://pipernet-mandate Provider, the resource://pipernet Resource wired to it, and the baseline Policy that allows read.

Web Console Setup

1. Start the runtime and open the web console:

   caracal up
   caracal status --ready

   Open the packaged web console at http://localhost:3001.

2. Create or select the target zone.

3. Create a control key with only the scopes the stage needs: read/write on app, provider, resource, and policy for apply; read for verify; read/delete for teardown.

4. Save the client_id and client_secret. STS resolves the zone from the bound control key; the secret stays retrievable from Services → Control through an audited reveal.

Run the pipeline

git clone https://github.com/Garudex-Labs/examples.git caracal-examples
cd caracal-examples/controlBootstrap
cp env.example .env
$EDITOR .env
. .env
npm run apply
npm run verify

apply is idempotent: rerunning it against an in-sync zone changes nothing, and rerunning it against a drifted zone converges the drift. Run teardown when you want to remove the environment:

npm run teardown

Files to study

File	Purpose
controlClient.mjs	Exchanges client credentials at STS and calls the Control API.
plan.mjs	Declares the desired environment, drift checks, scope tiers, and env-driven config.
apply.mjs	Reconciles the live zone with the plan.
verify.mjs	Read-only drift gate for CI.
teardown.mjs	Removes the environment in reverse dependency order.

Test

cd caracal-examples/controlBootstrap
npm test

The tests use a fake zone and mock transport and do not call a live Caracal stack.

Validate the workflow

Run apply twice, then verify, introduce one safe drift, and run verify again. Expect no second write on unchanged apply, a clean verification, then a non-zero drift result. Teardown must remove objects in dependency order without affecting objects outside the plan.

Failure point: credential boundary

Never give the example a root admin token or application credential. Control keys are zone-bound automation credentials; keep each pipeline stage least-privileged and short-lived.

Next Step

Continue to Check Provider Readiness before sending traffic through a provider-backed Gateway resource.