Skip to main content

Control Manifests

A control manifest describes organization resources that the Keeptrusts API owns. It is separate from the gateway's policy-config.yaml.

FileOwnerExamples
control-manifest.yamlKeeptrusts control planeIAM, members, teams, agents, budgets, organization policy
policy-config.yamlGateway runtimeProviders, routes, policy chain, runtime behavior

Do not combine the two schemas. The current control-manifest version is the string "1".

Supported resource groups​

Version 1 can reconcile:

  • hosted secret records through environment references;
  • IAM policies and roles;
  • teams, members, and memberships;
  • platform provider bundles;
  • agents, agent tags, gateway links, Context Fabric, MCP, and deployment settings;
  • budgets;
  • regulated-execution profiles;
  • workflow approval policies;
  • prompt-evaluation suites;
  • collaboration defaults;
  • hosted-gateway default policy and explicit agent bindings; and
  • organization browser-auth and SSO discovery policy.

The CLI orders operations by dependency. For example, it creates policies before roles that refer to them, roles before assignments, and agents before gateway links.

Start from current remote state​

Export a YAML baseline to stdout:

kt control export

Write it to a file:

kt control export --file control-manifest.yaml

Secret values are never exported. To include secret records as environment stubs:

kt control export \
  --file control-manifest.yaml \
  --include-secret-stubs

Review and replace each placeholder environment reference before applying. Never commit the environment's secret value.

By default, a failure while exporting any resource group prevents the partial manifest from being emitted. --allow-partial deliberately changes that behavior. If you use it for diagnosis, inspect every reported omission and do not treat the partial file as complete desired state.

Use --json when JSON is required; YAML is the default.

Minimal example​

version: "1"
resources:
  secrets:
    - name: openai-production-key
      env: KEEPTRUSTS_OPENAI_API_KEY
      description: Production provider credential
  iam:
    policies:
      - name: evidence-read
        description: Read governance evidence
        statements:
          - Effect: Allow
            Action:
              - events:read
              - exports:read
            Resource:
              - "*"
    roles:
      - name: evidence-reviewer
        policies:
          - evidence-read
  teams:
    - name: security-review
      description: Governance evidence reviewers
      members:
        - email: reviewer@example.com
          roles:
            - evidence-reviewer
  users:
    - email: reviewer@example.com
      teams:
        - security-review

Names are dependency references in the manifest. Keep them stable and unique within their resource type.

Plan before applying​

Compute a non-mutating plan:

kt control plan --file control-manifest.yaml

The plan reports creates, updates, deletes, no-ops, and ordered operations. Capture JSON for review automation:

kt control plan \
  --file control-manifest.yaml \
  --json

Without --prune, remote resources absent from the manifest remain in place. With --prune, the plan can include deletions:

kt control plan \
  --file control-manifest.yaml \
  --prune

Use prune only when the file is intentionally authoritative for every prune-supported resource it covers. A partial export and prune are an unsafe combination.

Apply the reviewed plan​

Interactive application:

kt control apply --file control-manifest.yaml

The CLI recomputes the plan, prints it, and prompts. In CI, use --yes to make the approved mutation intent explicit:

kt control apply \
  --file control-manifest.yaml \
  --yes \
  --json

Current --json apply output is noninteractive even if --yes is omitted. JSON mode is not a dry run; use kt control plan --json for that.

For a destructive reconciliation:

kt control plan --file control-manifest.yaml --prune --json
# Review the exact plan and required approvals.
kt control apply --file control-manifest.yaml --prune --yes --json

The plan is recomputed at apply time. Protect the interval between review and apply from unrelated administrative changes, and review the apply output for per-operation failures. Current JSON apply mode can return a successful process exit after individual operations fail, so automation must require applied == true and an empty failed array in addition to checking the exit status.

Secret handling​

A manifest secret has name, env, and optional description. It has no raw value field:

resources:
  secrets:
    - name: azure-openai-production-key
      env: KEEPTRUSTS_AZURE_OPENAI_API_KEY

Set the referenced variable only in the approved apply environment. Avoid shell-history arguments, generated logs, and committed .env files.

Operational checklist​

  1. Export a complete baseline with the required permissions.
  2. Store it in an access-controlled change workflow.
  3. Make one coherent change and validate every name reference.
  4. Run kt control plan.
  5. Review creates, updates, and especially deletes.
  6. Obtain required approval.
  7. Apply without prune unless deletion is explicitly intended.
  8. Inspect failures and verify the resulting resources through their owning list/detail surfaces.
  9. Review Trail evidence for the change.

Next steps​