Skip to main content

Control Manifests

A control manifest defines organization resources that the Verdictan API owns. It is different from the gateway's policy-config.yaml.

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

Do not use the two schemas together. This page defines control-manifest version "1".

Supported resource groups​

Version 1 can reconcile exported organization resources. These resources include hosted secret references, IAM, teams, members, agents, gateway links, budgets, approval policies, and organization authentication policy. Start from verdictan control export so that the manifest contains only resource groups that the authenticated organization can read.

The CLI orders dependent resources automatically. For example, it creates a policy before a role that refers to that policy. It creates an agent before a gateway link that refers to that agent.

Start from remote state​

Export a YAML baseline to stdout:

verdictan control export

Write it to a file:

verdictan control export --file control-manifest.yaml

The export does not include secret values. To include secret records as environment stubs, use this command:

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

Review each placeholder environment reference. Before you apply, replace each placeholder. Do not commit the environment's secret value.

By default, one resource-group export failure prevents all manifest output. --allow-partial changes that behavior. If you use it to investigate a failure, examine each reported omission. The output file is not a complete declaration of the declared state.

If the output must be JSON, use --json. YAML is the default format.

Minimal example​

version: "1"
resources:
  secrets:
    - name: openai-production-key
      env: VERDICTAN_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 in their resource type.

Plan before you apply​

Calculate a read-only plan:

verdictan control plan --file control-manifest.yaml

The plan reports creates, updates, deletes, no-ops, and the operation sequence. Capture JSON for review automation:

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

Without --prune, the CLI does not change remote resources missing from the manifest. With --prune, the plan can include deletions:

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

Use prune only for a file that is authoritative for all supported resources it includes. Do not use prune with an export that contains only some resources.

Apply the reviewed plan​

Interactive application:

verdictan control apply --file control-manifest.yaml

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

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

In --json mode, apply output is noninteractive without --yes. JSON mode is not a dry run. Use verdictan control plan --json for a dry run.

For a destructive reconciliation:

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

The CLI calculates the plan again when you apply it. Do not make unrelated administrative changes between plan review and application. Review the apply output for operation failures. Active JSON mode can return exit code zero after individual operations fail. Automation must verify that applied == true and that the failed array is empty. It must also verify the exit status.

Manage secrets​

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

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

Set the referenced variable only in the approved apply environment. Do not put it in shell-history arguments, generated logs, or committed .env files.

Apply checklist​

  1. Export a complete baseline with the necessary permissions.
  2. Store it in an access-controlled change workflow.
  3. Make one coherent change.
  4. Validate each name reference.
  5. Run verdictan control plan.
  6. Review creates, updates, and especially deletes.
  7. Get the necessary approval.
  8. Unless deletion is planned, apply without prune.
  9. Examine all failures.
  10. Verify the resources through their list or detail surfaces.
  11. Review Trail evidence for the change.

Next steps​